/*******************************************************************************
* Copyright (c) 2005, 2015 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.ui.commands;
import java.util.Collection;
import java.util.Map;
import org.eclipse.core.commands.Category;
import org.eclipse.core.commands.Command;
import org.eclipse.core.commands.CommandManager;
import org.eclipse.core.commands.IExecutionListener;
import org.eclipse.core.commands.IHandler;
import org.eclipse.core.commands.ParameterType;
import org.eclipse.core.commands.ParameterizedCommand;
import org.eclipse.core.commands.SerializationException;
import org.eclipse.core.commands.common.NotDefinedException;
import org.eclipse.ui.menus.UIElement;
import org.eclipse.ui.services.IDisposable;
/**
* <p>
* Provides services related to the command architecture within the workbench.
* This service can be used to access the set of commands and command
* categories.
* </p>
* <p>
* This service can be acquired from your service locator:
* <pre>
* ICommandService service = (ICommandService) getSite().getService(ICommandService.class);
* </pre>
* <ul>
* <li>This service is available globally.</li>
* </ul>
* </p>
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*
* @since 3.1
*/
public interface ICommandService extends IDisposable {
/**
* The identifier of the category in which all auto-generated commands will
* appear. This value must never be <code>null</code>.
*
* @since 3.2
*/
public static final String AUTOGENERATED_CATEGORY_ID = CommandManager.AUTOGENERATED_CATEGORY_ID;
/**
* Adds an execution listener to the command service. This listener will be
* notified as commands are executed.
* <p>
* <b>Note:</b> listeners should be removed when no longer necessary. If
* not, they will be removed when the IServiceLocator used to acquire this
* service is disposed.
* </p>
*
* @param listener
* The listener to add; must not be <code>null</code>.
* @see #removeExecutionListener(IExecutionListener)
*/
public void addExecutionListener(IExecutionListener listener);
/**
* Sets the name and description of the category for uncategorized commands.
* This is the category that will be returned if
* {@link #getCategory(String)} is called with <code>null</code>.
*
* @param name
* The name of the category for uncategorized commands; must not
* be <code>null</code>.
* @param description
* The description of the category for uncategorized commands;
* may be <code>null</code>.
* @since 3.2
*/
public void defineUncategorizedCategory(String name, String description);
/**
* <p>
* Returns a {@link ParameterizedCommand} with a command and
* parameterizations as specified in the provided
* <code>serializedParameterizedCommand</code> string. The
* <code>serializedParameterizedCommand</code> must use the format
* returned by {@link ParameterizedCommand#serialize()} and described in the
* Javadoc for that method.
* </p>
* <p>
* If a parameter id encoded in the
* <code>serializedParameterizedCommand</code> does not exist in the
* encoded command, that parameter id and value are ignored. A given
* parameter id should not be used more than once in
* <code>serializedParameterizedCommand</code>. This will not result in
* an exception, but the value of the parameter when the command is executed
* cannot be specified here.
* </p>
* <p>
* This method will never return <code>null</code>, however it may throw
* an exception if there is a problem processing the serialization string or
* the encoded command is undefined.
* </p>
*
* @param serializedParameterizedCommand
* a <code>String</code> representing a command id and
* parameter ids and values
* @return a <code>ParameterizedCommand</code> with the command and
* parameterizations encoded in the
* <code>serializedParameterizedCommand</code>
* @throws NotDefinedException
* if the command indicated in
* <code>serializedParameterizedCommand</code> is not defined
* @throws SerializationException
* if there is an error deserializing
* <code>serializedParameterizedCommand</code>
* @see ParameterizedCommand#serialize()
* @see CommandManager#deserialize(String)
* @since 3.2
*/
public ParameterizedCommand deserialize(
String serializedParameterizedCommand) throws NotDefinedException,
SerializationException;
/**
* Retrieves the category with the given identifier. If no such category
* exists, then an undefined category with the given id is created.
*
* @param categoryId
* The identifier to find. If the category is <code>null</code>,
* then a category suitable for uncategorized items is defined
* and returned.
* @return A category with the given identifier, either defined or
* undefined.
*/
public Category getCategory(String categoryId);
/**
* Retrieves the command with the given identifier. If no such command
* exists, then an undefined command with the given id is created.
*
* @param commandId
* The identifier to find; must not be <code>null</code>.
* @return A command with the given identifier, either defined or undefined.
*/
public Command getCommand(String commandId);
/**
* Returns the collection of all of the defined categories in the workbench.
*
* @return The collection of categories (<code>Category</code>) that are
* defined; never <code>null</code>, but may be empty.
* @since 3.2
*/
public Category[] getDefinedCategories();
/**
* Returns the collection of the identifiers for all of the defined
* categories in the workbench.
*
* @return The collection of category identifiers (<code>String</code>)
* that are defined; never <code>null</code>, but may be empty.
*/
public Collection getDefinedCategoryIds();
/**
* Returns the collection of the identifiers for all of the defined commands
* in the workbench.
*
* @return The collection of command identifiers (<code>String</code>)
* that are defined; never <code>null</code>, but may be empty.
*/
public Collection getDefinedCommandIds();
/**
* Returns the collection of all of the defined commands in the workbench.
*
* @return The collection of commands (<code>Command</code>) that are
* defined; never <code>null</code>, but may be empty.
* @since 3.2
*/
public Command[] getDefinedCommands();
/**
* Returns the collection of the identifiers for all of the defined command
* parameter types in the workbench.
*
* @return The collection of command parameter type identifiers (<code>String</code>)
* that are defined; never <code>null</code>, but may be empty.
* @since 3.2
*/
public Collection getDefinedParameterTypeIds();
/**
* Returns the collection of all of the defined command parameter types in
* the workbench.
*
* @return The collection of command parameter types (<code>ParameterType</code>)
* that are defined; never <code>null</code>, but may be empty.
* @since 3.2
*/
public ParameterType[] getDefinedParameterTypes();
/**
* Gets the help context identifier for a particular command. The command's
* handler is first checked for a help context identifier. If the handler
* does not have a help context identifier, then the help context identifier
* for the command is returned. If neither has a help context identifier,
* then <code>null</code> is returned.
*
* @param command
* The command for which the help context should be retrieved;
* must not be <code>null</code>.
* @return The help context identifier to use for the given command; may be
* <code>null</code>.
* @throws NotDefinedException
* If the given command is not defined.
* @since 3.2
*/
public String getHelpContextId(Command command) throws NotDefinedException;
/**
* Gets the help context identifier for a particular command. The command's
* handler is first checked for a help context identifier. If the handler
* does not have a help context identifier, then the help context identifier
* for the command is returned. If neither has a help context identifier,
* then <code>null</code> is returned.
*
* @param commandId
* The identifier of the command for which the help context
* should be retrieved; must not be <code>null</code>.
* @return The help context identifier to use for the given command; may be
* <code>null</code>.
* @throws NotDefinedException
* If the command with the given identifier is not defined.
* @since 3.2
*/
public String getHelpContextId(String commandId) throws NotDefinedException;
/**
* Retrieves the command parameter type with the given identifier. If no
* such parameter type exists, then an undefined parameter type with the
* given id is created.
*
* @param parameterTypeId
* The identifier to find; must not be <code>null</code>.
* @return A command parameter type with the given identifier, either
* defined or undefined.
* @since 3.2
*/
public ParameterType getParameterType(String parameterTypeId);
/**
* <p>
* Reads the command information from the registry and the preferences. This
* will overwrite any of the existing information in the command service.
* This method is intended to be called during start-up. When this method
* completes, this command service will reflect the current state of the
* registry and preference store.
* </p>
*/
public void readRegistry();
/**
* Removes an execution listener from the command service.
*
* @param listener
* The listener to remove; must not be <code>null</code>.
*/
public void removeExecutionListener(IExecutionListener listener);
/**
* Sets the help context identifier to associate with a particular handler.
*
* @param handler
* The handler with which to register a help context identifier;
* must not be <code>null</code>.
* @param helpContextId
* The help context identifier to register; may be
* <code>null</code> if the help context identifier should be
* removed.
* @since 3.2
*/
public void setHelpContextId(IHandler handler, String helpContextId);
/**
* Register that this element accepts callbacks for this parameterized
* command.
* <p>
* <b>Note:</b> elements should be removed when no longer necessary. If
* not, they will be removed when the IServiceLocator used to acquire this
* service is disposed.
* </p>
*
* @param command
* The parameterized command that is already specialized. Must
* not be <code>null</code>.
* @param element
* The callback to register for this specialized command
* instance. Must not be <code>null</code>.
* @return A reference for the registered element that can be used to
* unregister it.
* @throws NotDefinedException
* If the command included in the ParameterizedCommand is not
* defined, or the element is <code>null</code>.
* @since 3.3
* @see #unregisterElement(IElementReference)
*/
public IElementReference registerElementForCommand(
ParameterizedCommand command, UIElement element)
throws NotDefinedException;
/**
* Re-register a callback element provided by the ICommandService. This
* element reference must not currently be held by the ICommandService. i.e.
* it must have been removed using
* {@link #unregisterElement(IElementReference)}.
* <p>
* <b>Note:</b> elements should be removed when no longer necessary. If
* not, they will be removed when the IServiceLocator used to acquire this
* service is disposed.
* </p>
*
* @param elementReference
* The reference to re-register. Must not be <code>null</code>.
* @since 3.3
* @see #unregisterElement(IElementReference)
*/
public void registerElement(IElementReference elementReference);
/**
* Unregister an element callback. It will be removed from the
* ICommandService. The same service that is used to register an element for
* a command <b>must</b> be used to unregister the element.
*
* @param elementReference
* The callback reference that was provided by the command
* service on registration. Must not be <code>null</code>.
* @since 3.3
*/
public void unregisterElement(IElementReference elementReference);
/**
* Refresh any elements registered against the command with the given id.
* It allows the active handler the opportunity to provide user feedback. If
* the command is parameterized, some of the parameters can be specified to
* help narrow down which elements to refresh.
* <p>
* The service locator used in registering the element can also be used to
* scope the search. For example: if you wanted all elements for your
* command but only within the part's workbench window, you could use:
*
* <pre>
* Map filter = new HashMap();
* filter.put(IServiceScopes.WINDOW_SCOPE, getSite().getPage()
* .getWorkbenchWindow());
* commandService.refreshElements(commandId, filter);
* </pre>
*
* </p>
*
* @param commandId
* The command id to refresh if it has registered eleemnts.
* @param filter
* key-value pairs that can narrow down the callbacks to return.
* The parameters are <b>AND</b>ed together. This may be
* <code>null</code>.
* @since 3.3
*/
public void refreshElements(String commandId, Map filter);
}